Skip to content

v3.2: (Split and smaller!) Support ordered multipart including streaming #4745

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: v3.2-dev
Choose a base branch
from

Conversation

handrews
Copy link
Member

@handrews handrews commented Jun 21, 2025

**NOTE: This is just the new fields and their description, schema, and schema tests, with several things removed: 1.) the elaborate rules for determining type, which are now in PR #4743, 2.) the examples, which are in PR #4746 so they can be discussed in-depth and updated based on the pending Example Object changes. The contents of this PR are otherwise identical to #4589.


This adds support for all multipart media types that do not have named parts, including support for streaming such media types. Note that multipart/mixed defines the basic processing rules for all multipart types, and implementations that encounter unrecognized multipart subtypes are required to process them as multipart/mixed. Therefore support for multipart/mixed addresses all other subtypes to some degree.

This builds on the recent support for sequential media types:

  • multipart/mixed and similar meet the definition for a sequential media type, requiring it to be modeled as an array. This does use an expansive definition of "repeating the same structure", where the structure is literally any content with a media type.
  • As a sequential media type, it also supports itemSchema
  • Adding a parallel itemEncoding is the obvious solution to multipart/mixed streams requiring an Encoding Object
  • We have regularly received requests to support truly mixed multipart/mixed payloads, and previously claimed such support from 3.0.0 onwards, without actually supporting it. Adding prefixEncoding along with itemEncoding supports this use case with a clear parallel to prefixItems, which is the schema construct needed to support this case.
  • There is no need for a prefixSchema field because the streaming use case requires a repetition of the same schema for each item. Therefore all mixed use cases can use schema and prefixItems
  • schema changes are included in this pull request
  • schema changes are needed for this pull request but not done yet
  • no schema changes are needed for this pull request

@handrews handrews added this to the v3.2.0 milestone Jun 21, 2025
@handrews handrews requested review from a team as code owners June 21, 2025 01:20
@handrews handrews added the media and encoding Issues regarding media type support and how to encode data (outside of query/path params) label Jun 21, 2025
miqui
miqui previously approved these changes Jul 4, 2025
@handrews
Copy link
Member Author

handrews commented Jul 9, 2025

The most recent commit slightly relaxes the wording around using Encoding Objects and makes it clear that if you have more Encoding Objects than properties or items, this is not an error (which I think is not a change, but it depended on how you read a certain MUST).

I also relaxed the requirement that the property MUST exist "in the schema" (presumably under properties) as this is supplanted by the schema search guidance in PR #4743, which notes that you can just validate the data and then work with its type/structure directly whenever that is possible.

Copy link
Contributor

@ralfhandl ralfhandl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1, minor nits

@handrews
Copy link
Member Author

@ralfhandl updated - both concerns should be addressed now!

@lornajane lornajane requested review from lornajane, ralfhandl, miqui and a team July 17, 2025 16:54
ralfhandl
ralfhandl previously approved these changes Jul 18, 2025
@ralfhandl ralfhandl requested a review from a team July 18, 2025 07:34
handrews and others added 4 commits July 20, 2025 08:43
This adds support for all `multipart` media types that do not
have named parts, including support for streaming such media types.
Note that `multipart/mixed` defines the basic processing rules
for all `multipart` types, and implementations that encounter
unrecognized `multipart` subtypes are required to process them
as `multipart/mixed`.  Therefore support for `multipart/mixed`
addresses all other subtypes to some degree.

This builds on the recent support for sequential media types:

* `multipart/mixed` and similar meet the definition for
  a sequential media type, requiring it to be modeled as
  an array.  This does use an expansive definition of
  "repeating the same structure", where the structure is
  literally any content with a media type.
* As a sequential media type, it also supports `itemSchema`
* Adding a parallel `itemEncoding` is the obvious solution to
  `multipart/mixed` streams requiring an Encoding Object
* We have regularly received requests to support truly mixed
  `multipart/mixed` payloads, and previously claimed such support
  from 3.0.0 onwards, without actually supporting it.
  Adding `prefixEncoding` along with `itemEncoding` supports this
  use case with a clear parallel to `prefixItems`, which is the
  schema construct needed to support this case.
* There is no need for a `prefixSchema` field because the streaming
  use case requires a repetition of the same schema for each item.
  Therefore all mixed use cases can use `schema` and `prefixItems`
It's not an error if you have more encoding objects than instances.
Co-authored-by: Lorna Jane Mitchell <[email protected]>
@handrews
Copy link
Member Author

With apologies to @ralfhandl, I had to rebase this to fix conflicts after #4747 was merged. The conflict was just in the test file, and really I just removed the conflict markers as it put everything in the right place anyway. So nothing has actually changed.

@ralfhandl
Copy link
Contributor

nothing has actually changed

I trust you.

Just out of curiosity: how could I verify this?

@handrews
Copy link
Member Author

@ralfhandl well, it's the same commits in terms of what is in each commit, so me changing them would have been a lot more work. Honestly it hadn't occurred to me to need to check.

@handrews
Copy link
Member Author

@ralfhandl mostly, I put a lot of effort into making sure all of these PRs didn't conflict. The nested multipart was the only one that did, and I thought it would get done last so I'd easily be able to rebase it before the final review and just manage that. I didn't anticipate having to do it the other way around, and also when I first posted these they didn't need those tests, so things changed in-flight and messed up my no-conflicts, no-rebase plan :-/

@ralfhandl
Copy link
Contributor

No worries, I’ll re-approve once someone else has approved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
media and encoding Issues regarding media type support and how to encode data (outside of query/path params)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants